home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / NextDeveloper / Source / GNU / cc / gcc.info-5 (.txt) < prev    next >
GNU Info File  |  1993-10-21  |  49KB  |  854 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.54 from the input
  2. file gcc.texi.
  3.    This file documents the use and the internals of the GNU compiler.
  4.    Published by the Free Software Foundation 675 Massachusetts Avenue
  5. Cambridge, MA 02139 USA
  6.    Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided also
  12. that the sections entitled "GNU General Public License" and "Protect
  13. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  14. original, and provided that the entire resulting derived work is
  15. distributed under the terms of a permission notice identical to this
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that the sections entitled "GNU General Public
  19. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  20. permission notice, may be included in translations approved by the Free
  21. Software Foundation instead of in the original English.
  22. File: gcc.info,  Node: Installation,  Next: C Extensions,  Prev: Invoking GCC,  Up: Top
  23. Installing GNU CC
  24. *****************
  25.    Here is the procedure for installing GNU CC on a Unix system.
  26. * Menu:
  27. * Other Dir::     Compiling in a separate directory (not where the source is).
  28. * Cross-Compiler::   Building and installing a cross-compiler.
  29. * PA Install::    See below for installation on the HP Precision Architecture.
  30. * Sun Install::   See below for installation on the Sun.
  31. * 3b1 Install::   See below for installation on the 3b1.
  32. * Unos Install::  See below for installation on Unos (from CRDS).
  33. * VMS Install::   See below for installation on VMS.
  34. * WE32K Install:: See below for installation on the 3b* aside from the 3b1.
  35. * MIPS Install::  See below for installation on the MIPS Architecture.
  36. * Collect2::      How `collect2' works; how it finds `ld'.
  37. * Header Dirs::   Understanding the standard header file directories.
  38.   1. If you have built GNU CC previously in the same directory for a
  39.      different target machine, do `make distclean' to delete all files
  40.      that might be invalid.  One of the files this deletes is
  41.      `Makefile'; if `make distclean' complains that `Makefile' does not
  42.      exist, it probably means that the directory is already suitably
  43.      clean.
  44.   2. On a System V release 4 system, make sure `/usr/bin' precedes
  45.      `/usr/ucb' in `PATH'.  The `cc' command in `/usr/ucb' uses
  46.      libraries which have bugs.
  47.   3. Specify the host and target machine configurations.  You do this by
  48.      running the file `configure' with appropriate arguments.
  49.      If you are building a compiler to produce code for the machine it
  50.      runs on, specify just one machine type, with the `--target'
  51.      option; the host type will default to be the same as the target.
  52.      (For information on building a cross-compiler, see *Note
  53.      Cross-Compiler::.)  Here is an example:
  54.           configure --target=sparc-sun-sunos4.1
  55.      If you run `configure' without specifying configuration arguments,
  56.      `configure' tries to guess the type of host you are on, and uses
  57.      that configuration type for both host and target.  So you don't
  58.      need to specify a configuration, for building a native compiler,
  59.      unless `configure' cannot figure out what your configuration is.
  60.      A configuration name may be canonical or it may be more or less
  61.      abbreviated.
  62.      A canonical configuration name has three parts, separated by
  63.      dashes.  It looks like this: `CPU-COMPANY-SYSTEM'.  (The three
  64.      parts may themselves contain dashes; `configure' can figure out
  65.      which dashes serve which purpose.)  For example,
  66.      `m68k-sun-sunos4.1' specifies a Sun 3.
  67.      You can also replace parts of the configuration by nicknames or
  68.      aliases.  For example, `sun3' stands for `m68k-sun', so
  69.      `sun3-sunos4.1' is another way to specify a Sun 3.  You can also
  70.      use simply `sun3-sunos', since the version of SunOS is assumed by
  71.      default to be version 4.  `sun3-bsd' also works, since `configure'
  72.      knows that the only BSD variant on a Sun 3 is SunOS.
  73.      You can specify a version number after any of the system types,
  74.      and some of the CPU types.  In most cases, the version is
  75.      irrelevant, and will be ignored.  So you might as well specify the
  76.      version if you know it.
  77.      Here are the possible CPU types:
  78.           a29k, alpha, arm, cN, clipper, elxsi, h8300, hppa1.0, hppa1.1,
  79.           i370, i386, i486, i860, i960, m68000, m68k, m88k, mips,
  80.           ns32k, pyramid, romp, rs6000, sh, sparc, sparclite, vax,
  81.           we32k.
  82.      Here are the recognized company names.  As you can see, customary
  83.      abbreviations are used rather than the longer official names.
  84.           alliant, altos, apollo, att, bull, cbm, convergent, convex,
  85.           crds, dec, dg, dolphin, elxsi, encore, harris, hitachi, hp,
  86.           ibm, intergraph, isi, mips, motorola, ncr, next, ns, omron,
  87.           plexus, sequent, sgi, sony, sun, tti, unicom.
  88.      The company name is meaningful only to disambiguate when the rest
  89.      of the information supplied is insufficient.  You can omit it,
  90.      writing just `CPU-SYSTEM', if it is not needed.  For example,
  91.      `vax-ultrix4.2' is equivalent to `vax-dec-ultrix4.2'.
  92.      Here is a list of system types:
  93.           aix, acis, aos, bsd, clix, ctix, dgux, dynix, genix, hpux,
  94.           isc, linux, luna, lynxos, mach, minix, newsos, osf, osfrose,
  95.           riscos, sco, solaris, sunos, sysv, ultrix, unos, vms.
  96.      You can omit the system type; then `configure' guesses the
  97.      operating system from the CPU and company.
  98.      You can add a version number to the system type; this may or may
  99.      not make a difference.  For example, you can write `bsd4.3' or
  100.      `bsd4.4' to distinguish versions of BSD.  In practice, the version
  101.      number is most needed for `sysv3' and `sysv4', which are often
  102.      treated differently.
  103.      If you specify an impossible combination such as `i860-dg-vms',
  104.      then you may get an error message from `configure', or it may
  105.      ignore part of the information and do the best it can with the
  106.      rest.  `configure' always prints the canonical name for the
  107.      alternative that it used.
  108.      Often a particular model of machine has a name.  Many machine
  109.      names are recognized as aliases for CPU/company combinations.
  110.      Thus, the machine name `sun3', mentioned above, is an alias for
  111.      `m68k-sun'.  Sometimes we accept a company name as a machine name,
  112.      when the name is popularly used for a particular machine.  Here is
  113.      a table of the known machine names:
  114.           3300, 3b1, 3bN, 7300, altos3068, altos, apollo68, att-7300,
  115.           balance, convex-cN, crds, decstation-3100, decstation, delta,
  116.           encore, fx2800, gmicro, hp7NN, hp8NN, hp9k2NN, hp9k3NN,
  117.           hp9k7NN, hp9k8NN, iris4d, iris, isi68, m3230, magnum, merlin,
  118.           miniframe, mmax, news-3600, news800, news, next, pbd, pc532,
  119.           pmax, ps2, risc-news, rtpc, sun2, sun386i, sun386, sun3,
  120.           sun4, symmetry, tower-32, tower.
  121.      Remember that a machine name specifies both the cpu type and the
  122.      company name.
  123.      There are four additional options you can specify independently to
  124.      describe variant hardware and software configurations.  These are
  125.      `--with-gnu-as', `--with-gnu-ld', `--with-stabs' and `--nfp'.
  126.     `--with-gnu-as'
  127.           If you will use GNU CC with the GNU assembler (GAS), you
  128.           should declare this by using the `--with-gnu-as' option when
  129.           you run `configure'.
  130.           Using this option does not install GAS.  It only modifies the
  131.           output of GNU CC to work with GAS.  Building and installing
  132.           GAS is up to you.
  133.           The systems where it makes a difference whether you use GAS
  134.           are `hppa1.0-ANYTHING-ANYTHING', `hppa1.1-ANYTHING-ANYTHING',
  135.           `i386-ANYTHING-sysv', `i860-ANYTHING-bsd', `m68k-bull-sysv',
  136.           `m68k-hp-hpux', `m68k-sony-bsd', `m68k-altos-sysv',
  137.           `m68000-hp-hpux', `m68000-att-sysv', and `mips-ANY').  On any
  138.           other system, `--with-gnu-as' has no effect.
  139.           On the systems listed above (except for the HP-PA), if you
  140.           use GAS, you should also use the GNU linker (and specify
  141.           `--with-gnu-ld').
  142.     `--with-gnu-ld'
  143.           Specify the option `--with-gnu-ld' if you plan to use the GNU
  144.           linker with GNU CC.
  145.           This option does not cause the GNU linker to be installed; it
  146.           just modifies the behavior of GNU CC to work with the GNU
  147.           linker.  Specifically, it inhibits the installation of
  148.           `collect2', a program which otherwise serves as a front-end
  149.           for the system's linker on most configurations.
  150.     `--with-stabs'
  151.           On MIPS based systems and on Alphas, you must specify whether
  152.           you want GNU CC to create the normal ECOFF debugging format,
  153.           or to use BSD-style stabs passed through the ECOFF symbol
  154.           table.  The normal ECOFF debug format cannot fully handle
  155.           languages other than C.  BSD stabs format can handle other
  156.           languages, but it only works with the GNU debugger GDB.
  157.           Normally, GNU CC uses the ECOFF debugging format by default;
  158.           if you prefer BSD stabs, specify `--with-stabs' when you
  159.           configure GNU CC.
  160.           No matter which default you choose when you configure GNU CC,
  161.           the user can use the `-gcoff' and `-gstabs+' options to
  162.           specify explicitly the debug format for a particular
  163.           compilation.
  164.     `--nfp'
  165.           On certain systems, you must specify whether the machine has
  166.           a floating point unit.  These systems include
  167.           `m68k-sun-sunosN' and `m68k-isi-bsd'.  On any other system,
  168.           `--nfp' currently has no effect, though perhaps there are
  169.           other systems where it could usefully make a difference.
  170.      If you want to install your own homemade configuration files, you
  171.      can use `local' as the company name to access them.  If you use
  172.      configuration `CPU-local', the configuration name without the cpu
  173.      prefix is used to form the configuration file names.
  174.      Thus, if you specify `m68k-local', configuration uses files
  175.      `local.md', `local.h', `local.c', `xm-local.h', `t-local', and
  176.      `x-local', all in the directory `config/m68k'.
  177.      Here is a list of configurations that have special treatment or
  178.      special things you must know:
  179.     `alpha-*-osf1'
  180.           Systems using processors that implement the DEC Alpha
  181.           architecture and are running the OSF/1 operating system, for
  182.           example the DEC Alpha AXP systems.  (VMS on the Alpha is not
  183.           currently supported by GNU CC.)
  184.           GNU CC writes a `.verstamp' directive to the assembler output
  185.           file unless it is built as a cross-compiler.  It gets the
  186.           version to use from the system header file
  187.           `/usr/include/stamp.h'.  If you install a new version of
  188.           OSF/1, you should rebuild GCC to pick up the new version
  189.           stamp.
  190.           Note that since the Alpha is a 64-bit architecture,
  191.           cross-compilers from 32-bit machines will not generate as
  192.           efficient code as that generated when the compiler is running
  193.           on a 64-bit machine because many optimizations that depend on
  194.           being able to represent a word on the target in an integral
  195.           value on the host cannot be performed.  Building
  196.           cross-compilers on the Alpha for 32-bit machines has only
  197.           been tested in a few cases and may not work properly.
  198.           `make compare' may fail on some versions of OSF/1 unless you
  199.           add `-save-temps' to `BOOT_CFLAGS'.  This forces a fixed name
  200.           to be used for the assembler input file instead of a random
  201.           name in `/tmp'.  The name of the assembler input file is
  202.           stored in the object file and will cause miscompared if it
  203.           differs between the `stage1' and `stage2' compilations.
  204.           GNU CC now supports both the native (ECOFF) debugging format
  205.           used by DBX and GDB and an encapsulated STABS format for use
  206.           only with GDB.  See the discussion of the `--with-stabs'
  207.           option of `configure' above for more information on these
  208.           formats and how to select them.
  209.           There is a bug in DEC's assembler that produces incorrect
  210.           line numbers for ECOFF format when the `.align' directive is
  211.           used.  To work around this problem, GNU CC will not emit such
  212.           alignment directives even if optimization is being performed
  213.           if it is writing ECOFF format debugging information.
  214.           Unfortunately, this has the very undesirable side-effect that
  215.           code addresses when `-O' is specified are different depending
  216.           on whether or not `-g' is also specified.
  217.           To avoid this behavior, specify `-gstabs+' and use GDB
  218.           instead of DBX.  DEC is now aware of this problem with the
  219.           assembler and hopes to provide a fix shortly.
  220.     `a29k'
  221.           AMD Am29k-family processors.  These are normally used in
  222.           embedded applications.  There are no standard Unix
  223.           configurations.  This configuration corresponds to AMD's
  224.           standard calling sequence and binary interface and is
  225.           compatible with other 29k tools.
  226.           You may need to make a variant of the file `a29k.h' for your
  227.           particular configuration.
  228.     `a29k-*-bsd'
  229.           AMD Am29050 used in a system running a variant of BSD Unix.
  230.     `elxsi-elxsi-bsd'
  231.           The Elxsi's C compiler has known limitations that prevent it
  232.           from compiling GNU C.  Please contact `mrs@cygnus.com' for
  233.           more details.
  234.     `hppa*-*-*'
  235.           Using GAS is highly recommended for all HP-PA configurations.
  236.           See *Note PA Install:: for the special procedures needed to
  237.           compile GNU CC for the HP-PA.
  238.     `i386-*-sco'
  239.           Compilation with RCC is recommended.  Also, it may be a good
  240.           idea to link with GNU malloc instead of the malloc that comes
  241.           with the system.
  242.     `i386-*-sco3.2.4'
  243.           Use this configuration for SCO release 3.2 version 4.
  244.     `i386-*-isc'
  245.           It may be good idea to link with GNU malloc instead of the
  246.           malloc that comes with the system.
  247.     `i386-*-esix'
  248.           It may be good idea to link with GNU malloc instead of the
  249.           malloc that comes with the system.
  250.     `i386-ibm-aix'
  251.           You need to use GAS version 2.1 or later, and and LD from GNU
  252.           binutils version 2.2 or later.
  253.     `i386-sequent'
  254.           Go to the Berkeley universe before compiling.  In addition,
  255.           you probably need to create a file named `string.h'
  256.           containing just one line: `#include <strings.h>'.
  257.     `i386-sun-sunos4'
  258.           You may find that you need another version of GNU CC to begin
  259.           bootstrapping with, since the current version when built with
  260.           the system's own compiler seems to get an infinite loop
  261.           compiling part of `libgcc2.c'.  GNU CC version 2 compiled
  262.           with GNU CC (any version) seems not to have this problem.
  263.     `m68000-att'
  264.           AT&T 3b1, a.k.a. 7300 PC.  Special procedures are needed to
  265.           compile GNU CC with this machine's standard C compiler, due
  266.           to bugs in that compiler.  *Note 3b1 Install::.  You can
  267.           bootstrap it more easily with previous versions of GNU CC if
  268.           you have them.
  269.     `m68000-hp-bsd'
  270.           HP 9000 series 200 running BSD.  Note that the C compiler
  271.           that comes with this system cannot compile GNU CC; contact
  272.           `law@cs.utah.edu' to get binaries of GNU CC for bootstrapping.
  273.     `m68k-altos'
  274.           Altos 3068.  You must use the GNU assembler, linker and
  275.           debugger.  Also, you must fix a kernel bug.  Details in the
  276.           file `README.ALTOS'.
  277.     `m68k-bull-sysv'
  278.           Bull DPX/2 series 200 and 300 with BOS-2.00.45 up to
  279.           BOS-2.01. GNU CC works either with native assembler or GNU
  280.           assembler. You can use GNU assembler with native coff
  281.           generation by providing `--gas' to the configure script or
  282.           use GNU assembler with dbx-in-coff encapsulation by providing
  283.           `--gas --stabs'. For any problem with native assembler or for
  284.           availability of the DPX/2 port of GAS, contact
  285.           `F.Pierresteguy@frcl.bull.fr'.
  286.     `m68k-hp-hpux'
  287.           HP 9000 series 300 or 400 running HP-UX.  HP-UX version 8.0
  288.           has a bug in the assembler that prevents compilation of GNU
  289.           CC.  To fix it, get patch PHCO_0800 from HP.
  290.           In addition, `--gas' does not currently work with this
  291.           configuration.  Changes in HP-UX have broken the library
  292.           conversion tool and the linker.
  293.     `m68k-sun'
  294.           Sun 3.  We do not provide a configuration file to use the Sun
  295.           FPA by default, because programs that establish signal
  296.           handlers for floating point traps inherently cannot work with
  297.           the FPA.
  298.     `m88k-*-svr3'
  299.           Motorola m88k running the AT&T/Unisoft/Motorola V.3 reference
  300.           port.  These systems tend to use the Green Hills C, revision
  301.           1.8.5, as the standard C compiler.  There are apparently bugs
  302.           in this compiler that result in object files differences
  303.           between stage 2 and stage 3.  If this happens, make the stage
  304.           4 compiler and compare it to the stage 3 compiler.  If the
  305.           stage 3 and stage 4 object files are identical, this suggests
  306.           you encountered a problem with the standard C compiler; the
  307.           stage 3 and 4 compilers may be usable.
  308.           It is best, however, to use an older version of GNU CC for
  309.           bootstrapping if you have one.
  310.     `m88k-*-dgux'
  311.           Motorola m88k running DG/UX.  To build native or cross
  312.           compilers on DG/UX, you must first change to the 88open BCS
  313.           software development environment.  This is done by issuing
  314.           this command:
  315.                eval `sde-target m88kbcs`
  316.     `m88k-tektronix-sysv3'
  317.           Tektronix XD88 running UTekV 3.2e.  Do not turn on
  318.           optimization while building stage1 if you bootstrap with the
  319.           buggy Green Hills compiler.  Also, The bundled LAI System V
  320.           NFS is buggy so if you build in an NFS mounted directory,
  321.           start from a fresh reboot, or avoid NFS all together.
  322.           Otherwise you may have trouble getting clean comparisons
  323.           between stages.
  324.     `mips-mips-bsd'
  325.           MIPS machines running the MIPS operating system in BSD mode.
  326.           It's possible that some old versions of the system lack the
  327.           functions `memcpy', `memcmp', and `memset'.  If your system
  328.           lacks these, you must remove or undo the definition of
  329.           `TARGET_MEM_FUNCTIONS' in `mips-bsd.h'.
  330.     `mips-sgi-*'
  331.           Silicon Graphics MIPS machines running IRIX.  In order to
  332.           compile GCC on an SGI the "c.hdr.lib" option must be
  333.           installed from the CD-ROM supplied from Silicon Graphics.
  334.           This is found on the 2nd CD in release 4.0.1.
  335.     `mips-sony-sysv'
  336.           Sony MIPS NEWS.  This works in NEWSOS 5.0.1, but not in 5.0.2
  337.           (which uses ELF instead of COFF).  Support for 5.0.2 will
  338.           probably be provided soon by volunteers.  In particular, the
  339.           linker does not like the code generated by GCC when shared
  340.           libraries are linked in.
  341.     `ns32k-encore'
  342.           Encore ns32000 system.  Encore systems are supported only
  343.           under BSD.
  344.     `ns32k-*-genix'
  345.           National Semiconductor ns32000 system.  Genix has bugs in
  346.           `alloca' and `malloc'; you must get the compiled versions of
  347.           these from GNU Emacs.
  348.     `ns32k-sequent'
  349.           Go to the Berkeley universe before compiling.  In addition,
  350.           you probably need to create a file named `string.h'
  351.           containing just one line: `#include <strings.h>'.
  352.     `ns32k-utek'
  353.           UTEK ns32000 system ("merlin").  The C compiler that comes
  354.           with this system cannot compile GNU CC; contact
  355.           `tektronix!reed!mason' to get binaries of GNU CC for
  356.           bootstrapping.
  357.     `romp-*-aos'
  358.     `romp-*-mach'
  359.           The only operating systems supported for the IBM RT PC are
  360.           AOS and MACH.  GNU CC does not support AIX running on the RT.
  361.           We recommend you compile GNU CC with an earlier version of
  362.           itself; if you compile GNU CC with `hc', the Metaware
  363.           compiler, it will work, but you will get mismatches between
  364.           the stage 2 and stage 3 compilers in various files.  These
  365.           errors are minor differences in some floating-point constants
  366.           and can be safely ignored; the stage 3 compiler is correct.
  367.     `rs6000-*-aix'
  368.           *Read the file `README.RS6000' for information on how to get
  369.           a fix for problems in the IBM assembler that interfere with
  370.           GNU CC.* You must either obtain the new assembler or avoid
  371.           using the `-g' switch.  Note that `Makefile.in' uses `-g' by
  372.           default when compiling `libgcc2.c'.
  373.           The PowerPC and POWER2 architectures are now supported, but
  374.           have not been extensively tested due to lack of appropriate
  375.           systems.  Only AIX is supported on the PowerPC.
  376.           XLC version 1.3.0.0 will miscompile `jump.c'.  XLC version
  377.           1.3.0.1 or later fixes this problem.  We do not yet have a
  378.           PTF number for this fix.
  379.     `vax-dec-ultrix'
  380.           Don't try compiling with Vax C (`vcc').  It produces
  381.           incorrect code in some cases (for example, when `alloca' is
  382.           used).
  383.           Meanwhile, compiling `cp-parse.c' with pcc does not work
  384.           because of an internal table size limitation in that
  385.           compiler.  To avoid this problem, compile just the GNU C
  386.           compiler first, and use it to recompile building all the
  387.           languages that you want to run.
  388.      Here we spell out what files will be set up by `configure'.
  389.      Normally you need not be concerned with these files.
  390.         * A symbolic link named `config.h' is made to the top-level
  391.           config file for the machine you will run the compiler on
  392.           (*note Config::.).  This file is responsible for defining
  393.           information about the host machine.  It includes `tm.h'.
  394.           The top-level config file is located in the subdirectory
  395.           `config'.  Its name is always `xm-SOMETHING.h'; usually
  396.           `xm-MACHINE.h', but there are some exceptions.
  397.           If your system does not support symbolic links, you might
  398.           want to set up `config.h' to contain a `#include' command
  399.           which refers to the appropriate file.
  400.         * A symbolic link named `tconfig.h' is made to the top-level
  401.           config file for your target machine.  This is used for
  402.           compiling certain programs to run on that machine.
  403.         * A symbolic link named `tm.h' is made to the
  404.           machine-description macro file for your target machine.  It
  405.           should be in the subdirectory `config' and its name is often
  406.           `MACHINE.h'.
  407.         * A symbolic link named `md' will be made to the machine
  408.           description pattern file.  It should be in the `config'
  409.           subdirectory and its name should be `MACHINE.md'; but MACHINE
  410.           is often not the same as the name used in the `tm.h' file
  411.           because the `md' files are more general.
  412.         * A symbolic link named `aux-output.c' will be made to the
  413.           output subroutine file for your machine.  It should be in the
  414.           `config' subdirectory and its name should be `MACHINE.c'.
  415.         * The command file `configure' also constructs the file
  416.           `Makefile' by adding some text to the template file
  417.           `Makefile.in'.  The additional text comes from files in the
  418.           `config' directory, named `t-TARGET' and `x-HOST'.  If these
  419.           files do not exist, it means nothing needs to be added for a
  420.           given target or host.
  421.   4. The standard directory for installing GNU CC is `/usr/local/lib'.
  422.      If you want to install its files somewhere else, specify
  423.      `--prefix=DIR' when you run `configure'.  Here DIR is a directory
  424.      name to use instead of `/usr/local' for all purposes with one
  425.      exception: the directory `/usr/local/include' is searched for
  426.      header files no matter where you install the compiler.
  427.   5. Specify `--local-prefix=DIR' if you want the compiler to search
  428.      directory `DIR/include' for header files *instead* of
  429.      `/usr/local/include'.  (This is for systems that have different
  430.      conventions for where to put site-specific things.)
  431.   6. Make sure the Bison parser generator is installed.  (This is
  432.      unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
  433.      more recent than `c-parse.y' and `cexp.y' and you do not plan to
  434.      change the `.y' files.)
  435.      Bison versions older than Sept 8, 1988 will produce incorrect
  436.      output for `c-parse.c'.
  437.   7. Build the compiler.  Just type `make LANGUAGES=c' in the compiler
  438.      directory.
  439.      `LANGUAGES=c' specifies that only the C compiler should be
  440.      compiled.  The makefile normally builds compilers for all the
  441.      supported languages; currently, C, C++ and Objective C.  However,
  442.      C is the only language that is sure to work when you build with
  443.      other non-GNU C compilers.  In addition, building anything but C
  444.      at this stage is a waste of time.
  445.      In general, you can specify the languages to build by typing the
  446.      argument `LANGUAGES="LIST"', where LIST is one or more words from
  447.      the list `c', `c++', and `objective-c'.
  448.      Ignore any warnings you may see about "statement not reached" in
  449.      `insn-emit.c'; they are normal.  Also, warnings about "unknown
  450.      escape sequence" are normal in `genopinit.c' and perhaps some
  451.      other files.  Any other compilation errors may represent bugs in
  452.      the port to your machine or operating system, and should be
  453.      investigated and reported (*note Bugs::.).
  454.      Some commercial compilers fail to compile GNU CC because they have
  455.      bugs or limitations.  For example, the Microsoft compiler is said
  456.      to run out of macro space.  Some Ultrix compilers run out of
  457.      expression space; then you need to break up the statement where
  458.      the problem happens.
  459.      If you are building with a previous GNU C compiler, do not use
  460.      `CC=gcc' on the make command or by editing the Makefile.  Instead,
  461.      use a full pathname to specify the compiler, such as
  462.      `CC=/usr/local/bin/gcc'.  This is because make might execute the
  463.      `gcc' in the current directory before all of the compiler
  464.      components have been built.
  465.   8. If you are building a cross-compiler, stop here.  *Note
  466.      Cross-Compiler::.
  467.   9. Move the first-stage object files and executables into a
  468.      subdirectory with this command:
  469.           make stage1
  470.      The files are moved into a subdirectory named `stage1'.  Once
  471.      installation is complete, you may wish to delete these files with
  472.      `rm -r stage1'.
  473.  10. If you have chosen a configuration for GNU CC which requires other
  474.      GNU tools (such as GAS or the GNU linker) instead of the standard
  475.      system tools, install the required tools in the `stage1'
  476.      subdirectory under the names `as', `ld' or whatever is
  477.      appropriate.  This will enable the stage 1 compiler to find the
  478.      proper tools in the following stage.
  479.      Alternatively, you can do subsequent compilation using a value of
  480.      the `PATH' environment variable such that the necessary GNU tools
  481.      come before the standard system tools.
  482.  11. Recompile the compiler with itself, with this command:
  483.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O"
  484.      This is called making the stage 2 compiler.
  485.      The command shown above builds compilers for all the supported
  486.      languages.  If you don't want them all, you can specify the
  487.      languages to build by typing the argument `LANGUAGES="LIST"'.  LIST
  488.      should contain one or more words from the list `c', `c++',
  489.      `objective-c', and `proto'.  Separate the words with spaces.
  490.      `proto' stands for the programs `protoize' and `unprotoize'; they
  491.      are not a separate language, but you use `LANGUAGES' to enable or
  492.      disable their installation.
  493.      If you are going to build the stage 3 compiler, then you might
  494.      want to build only the C language in stage 2.
  495.      Once you have built the stage 2 compiler, if you are short of disk
  496.      space, you can delete the subdirectory `stage1'.
  497.      On a 68000 or 68020 system lacking floating point hardware, unless
  498.      you have selected a `tm.h' file that expects by default that there
  499.      is no such hardware, do this instead:
  500.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O -msoft-float"
  501.  12. If you wish to test the compiler by compiling it with itself one
  502.      more time, install any other necessary GNU tools (such as GAS or
  503.      the GNU linker) in the `stage2' subdirectory as you did in the
  504.      `stage1' subdirectory, then do this:
  505.           make stage2
  506.           make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  507.      This is called making the stage 3 compiler.  Aside from the `-B'
  508.      option, the compiler options should be the same as when you made
  509.      the stage 2 compiler.  But the `LANGUAGES' option need not be the
  510.      same.  The command shown above builds compilers for all the
  511.      supported languages; if you don't want them all, you can specify
  512.      the languages to build by typing the argument `LANGUAGES="LIST"',
  513.      as described above.
  514.      Then compare the latest object files with the stage 2 object
  515.      files--they ought to be identical, unless they contain time stamps.
  516.      You can compare the files, disregarding the time stamps if any,
  517.      like this:
  518.           make compare
  519.      This will mention any object files that differ between stage 2 and
  520.      stage 3.  Any difference, no matter how innocuous, indicates that
  521.      the stage 2 compiler has compiled GNU CC incorrectly, and is
  522.      therefore a potentially serious bug which you should investigate
  523.      and report (*note Bugs::.).
  524.      If your system does not put time stamps in the object files, then
  525.      this is a faster way to compare them (using the Bourne shell):
  526.           for file in *.o; do
  527.           cmp $file stage2/$file
  528.           done
  529.      If you have built the compiler with the `-mno-mips-tfile' option on
  530.      MIPS machines, you will not be able to compare the files.
  531.      The Alpha stores file names in the object files and `make compare'
  532.      does not know how to ignore them, so normally you cannot compare
  533.      on the Alpha.  However, if you use the `-save-temps' option when
  534.      compiling *both* stage 2 and stage 3, this causes the same file
  535.      names to be used in both stages; then you can do the comparison.
  536.  13. Build the Objective C library (if you have built the Objective C
  537.      compiler).  Here is the command to do this:
  538.           make objc-runtime CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  539.  14. Install the compiler driver, the compiler's passes and run-time
  540.      support with `make install'.  Use the same value for `CC',
  541.      `CFLAGS' and `LANGUAGES' that you used when compiling the files
  542.      that are being installed.  One reason this is necessary is that
  543.      some versions of Make have bugs and recompile files gratuitously
  544.      when you do this step.  If you use the same variable values, those
  545.      files will be recompiled properly.
  546.      For example, if you have built the stage 2 compiler, you can use
  547.      the following command:
  548.           make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="LIST"
  549.      This copies the files `cc1', `cpp' and `libgcc.a' to files `cc1',
  550.      `cpp' and `libgcc.a' in the directory
  551.      `/usr/local/lib/gcc-lib/TARGET/VERSION', which is where the
  552.      compiler driver program looks for them.  Here TARGET is the target
  553.      machine type specified when you ran `configure', and VERSION is
  554.      the version number of GNU CC.  This naming scheme permits various
  555.      versions and/or cross-compilers to coexist.
  556.      This also copies the driver program `xgcc' into
  557.      `/usr/local/bin/gcc', so that it appears in typical execution
  558.      search paths.
  559.      On some systems, this command causes recompilation of some files.
  560.      This is usually due to bugs in `make'.  You should either ignore
  561.      this problem, or use GNU Make.
  562.      *Warning: there is a bug in `alloca' in the Sun library.  To avoid
  563.      this bug, be sure to install the executables of GNU CC that were
  564.      compiled by GNU CC.  (That is, the executables from stage 2 or 3,
  565.      not stage 1.)  They use `alloca' as a built-in function and never
  566.      the one in the library.*
  567.      (It is usually better to install GNU CC executables from stage 2
  568.      or 3, since they usually run faster than the ones compiled with
  569.      some other compiler.)
  570.  15. Install the Objective C library (if you are installing the
  571.      Objective C compiler).  Here is the command to do this:
  572.           make install-libobjc CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  573.  16. If you're going to use C++, it's likely that you need to also
  574.      install the libg++ distribution.  It should be available from the
  575.      same place where you got the GNU C distribution.  Just as GNU C
  576.      does not distribute a C runtime library, it also does not include
  577.      a C++ run-time library.  All I/O functionality, special class
  578.      libraries, etc., are available in the libg++ distribution.
  579. File: gcc.info,  Node: Other Dir,  Next: Cross-Compiler,  Up: Installation
  580. Compilation in a Separate Directory
  581. ===================================
  582.    If you wish to build the object files and executables in a directory
  583. other than the one containing the source files, here is what you must
  584. do differently:
  585.   1. Make sure you have a version of Make that supports the `VPATH'
  586.      feature.  (GNU Make supports it, as do Make versions on most BSD
  587.      systems.)
  588.   2. If you have ever run `configure' in the source directory, you must
  589.      undo the configuration.  Do this by running:
  590.           make distclean
  591.   3. Go to the directory in which you want to build the compiler before
  592.      running `configure':
  593.           mkdir gcc-sun3
  594.           cd gcc-sun3
  595.      On systems that do not support symbolic links, this directory must
  596.      be on the same file system as the source code directory.
  597.   4. Specify where to find `configure' when you run it:
  598.           ../gcc/configure ...
  599.      This also tells `configure' where to find the compiler sources;
  600.      `configure' takes the directory from the file name that was used to
  601.      invoke it.  But if you want to be sure, you can specify the source
  602.      directory with the `--srcdir' option, like this:
  603.           ../gcc/configure --srcdir=../gcc sun3
  604.      The directory you specify with `--srcdir' need not be the same as
  605.      the one that `configure' is found in.
  606.    Now, you can run `make' in that directory.  You need not repeat the
  607. configuration steps shown above, when ordinary source files change.  You
  608. must, however, run `configure' again when the configuration files
  609. change, if your system does not support symbolic links.
  610. File: gcc.info,  Node: Cross-Compiler,  Next: PA Install,  Prev: Other Dir,  Up: Installation
  611. Building and Installing a Cross-Compiler
  612. ========================================
  613.    GNU CC can function as a cross-compiler for many machines, but not
  614.    * Cross-compilers for the Mips as target using the Mips assembler
  615.      currently do not work, because the auxiliary programs
  616.      `mips-tdump.c' and `mips-tfile.c' can't be compiled on anything
  617.      but a Mips.  It does work to cross compile for a Mips if you use
  618.      the GNU assembler and linker.
  619.    * Cross-compilers between machines with different floating point
  620.      formats have not all been made to work.  GNU CC now has a floating
  621.      point emulator with which these can work, but each target machine
  622.      description needs to be updated to take advantage of it.
  623.    * Cross-compilation between machines of different word sizes has not
  624.      really been addressed yet.
  625.    Since GNU CC generates assembler code, you probably need a
  626. cross-assembler that GNU CC can run, in order to produce object files.
  627. If you want to link on other than the target machine, you need a
  628. cross-linker as well.  You also need header files and libraries suitable
  629. for the target machine that you can install on the host machine.
  630. * Menu:
  631. * Steps of Cross::      Using a cross-compiler involves several steps
  632.                           that may be carried out on different machines.
  633. * Configure Cross::     Configuring a cross-compiler.
  634. * Tools and Libraries:: Where to put the linker and assembler, and the C library.
  635. * Cross Headers::       Finding and installing header files
  636.                           for a cross-compiler.
  637. * Cross Runtime::       Supplying arithmetic runtime routines (`libgcc1.a').
  638. * Build Cross::         Actually compiling the cross-compiler.
  639. File: gcc.info,  Node: Steps of Cross,  Next: Configure Cross,  Up: Cross-Compiler
  640. Steps of Cross-Compilation
  641. --------------------------
  642.    To compile and run a program using a cross-compiler involves several
  643. steps:
  644.    * Run the cross-compiler on the host machine to produce assembler
  645.      files for the target machine.  This requires header files for the
  646.      target machine.
  647.    * Assemble the files produced by the cross-compiler.  You can do this
  648.      either with an assembler on the target machine, or with a
  649.      cross-assembler on the host machine.
  650.    * Link those files to make an executable.  You can do this either
  651.      with a linker on the target machine, or with a cross-linker on the
  652.      host machine.  Whichever machine you use, you need libraries and
  653.      certain startup files (typically `crt....o') for the target
  654.      machine.
  655.    It is most convenient to do all of these steps on the same host
  656. machine, since then you can do it all with a single invocation of GNU
  657. CC.  This requires a suitable cross-assembler and cross-linker.  For
  658. some targets, the GNU assembler and linker are available.
  659. File: gcc.info,  Node: Configure Cross,  Next: Tools and Libraries,  Prev: Steps of Cross,  Up: Cross-Compiler
  660. Configuring a Cross-Compiler
  661. ----------------------------
  662.    To build GNU CC as a cross-compiler, you start out by running
  663. `configure'.  You must specify two different configurations, the host
  664. and the target.  Use the `--host=HOST' option for the host and
  665. `--target=TARGET' to specify the target type.  For example, here is how
  666. to configure for a cross-compiler that runs on a hypothetical Intel 386
  667. system and produces code for an HP 68030 system running BSD:
  668.      configure --target=m68k-hp-bsd4.3 --host=i386-bozotheclone-bsd4.3
  669. File: gcc.info,  Node: Tools and Libraries,  Next: Cross Headers,  Prev: Configure Cross,  Up: Cross-Compiler
  670. Tools and Libraries for a Cross-Compiler
  671. ----------------------------------------
  672.    If you have a cross-assembler and cross-linker available, you should
  673. install them now.  Put them in the directory `/usr/local/TARGET/bin'.
  674. Here is a table of the tools you should put in this directory:
  675.      This should be the cross-assembler.
  676.      This should be the cross-linker.
  677.      This should be the cross-archiver: a program which can manipulate
  678.      archive files (linker libraries) in the target machine's format.
  679. `ranlib'
  680.      This should be a program to construct a symbol table in an archive
  681.      file.
  682.    The installation of GNU CC will find these programs in that
  683. directory, and copy or link them to the proper place to for the
  684. cross-compiler to find them when run later.
  685.    The easiest way to provide these files is to build the Binutils
  686. package and GAS.  Configure them with the same `--host' and `--target'
  687. options that you use for configuring GNU CC, then build and install
  688. them.  They install their executables automatically into the proper
  689. directory.  Alas, they do not support all the targets that GNU CC
  690. supports.
  691.    If you want to install libraries to use with the cross-compiler,
  692. such as a standard C library, put them in the directory
  693. `/usr/local/TARGET/lib'; installation of GNU CC copies all all the
  694. files in that subdirectory into the proper place for GNU CC to find
  695. them and link with them.  Here's an example of copying some libraries
  696. from a target machine:
  697.      ftp TARGET-MACHINE
  698.      lcd /usr/local/TARGET/lib
  699.      cd /lib
  700.      get libc.a
  701.      cd /usr/lib
  702.      get libg.a
  703.      get libm.a
  704.      quit
  705. The precise set of libraries you'll need, and their locations on the
  706. target machine, vary depending on its operating system.
  707.    Many targets require "start files" such as `crt0.o' and `crtn.o'
  708. which are linked into each executable; these too should be placed in
  709. `/usr/local/TARGET/lib'.  There may be several alternatives for
  710. `crt0.o', for use with profiling or other compilation options.  Check
  711. your target's definition of `STARTFILE_SPEC' to find out what start
  712. files it uses.  Here's an example of copying these files from a target
  713. machine:
  714.      ftp TARGET-MACHINE
  715.      lcd /usr/local/TARGET/lib
  716.      prompt
  717.      cd /lib
  718.      mget *crt*.o
  719.      cd /usr/lib
  720.      mget *crt*.o
  721.      quit
  722. File: gcc.info,  Node: Cross Runtime,  Next: Build Cross,  Prev: Cross Headers,  Up: Cross-Compiler
  723. `libgcc.a' and Cross-Compilers
  724. ------------------------------
  725.    Code compiled by GNU CC uses certain runtime support functions
  726. implicitly.  Some of these functions can be compiled successfully with
  727. GNU CC itself, but a few cannot be.  These problem functions are in the
  728. source file `libgcc1.c'; the library made from them is called
  729. `libgcc1.a'.
  730.    When you build a native compiler, these functions are compiled with
  731. some other compiler-the one that you use for bootstrapping GNU CC.
  732. Presumably it knows how to open code these operations, or else knows how
  733. to call the run-time emulation facilities that the machine comes with.
  734. But this approach doesn't work for building a cross-compiler.  The
  735. compiler that you use for building knows about the host system, not the
  736. target system.
  737.    So, when you build a cross-compiler you have to supply a suitable
  738. library `libgcc1.a' that does the job it is expected to do.
  739.    To compile `libgcc1.c' with the cross-compiler itself does not work.
  740. The functions in this file are supposed to implement arithmetic
  741. operations that GNU CC does not know how to open code, for your target
  742. machine.  If these functions are compiled with GNU CC itself, they will
  743. compile into infinite recursion.
  744.    On any given target, most of these functions are not needed.  If GNU
  745. CC can open code an arithmetic operation, it will not call these
  746. functions to perform the operation.  It is possible that on your target
  747. machine, none of these functions is needed.  If so, you can supply an
  748. empty library as `libgcc1.a'.
  749.    Many targets need library support only for multiplication and
  750. division.  If you are linking with a library that contains functions for
  751. multiplication and division, you can tell GNU CC to call them directly
  752. by defining the macros `MULSI3_LIBCALL', and the like.  These macros
  753. need to be defined in the target description macro file.  For some
  754. targets, they are defined already.  This may be sufficient to avoid the
  755. need for libgcc1.a; if so, you can supply an empty library.
  756.    Some targets do not have floating point instructions; they need other
  757. functions in `libgcc1.a', which do floating arithmetic.  Recent
  758. versions of GNU CC have a file which emulates floating point.  With a
  759. certain amount of work, you should be able to construct a floating
  760. point emulator that can be used as `libgcc1.a'.  Perhaps future
  761. versions will contain code to do this automatically and conveniently.
  762. That depends on whether someone wants to implement it.
  763.    If your target system has another C compiler, you can configure GNU
  764. CC as a native compiler on that machine, build just `libgcc1.a' with
  765. `make libgcc1.a' on that machine, and use the resulting file with the
  766. cross-compiler.  To do this, execute the following on the target
  767. machine:
  768.      cd TARGET-BUILD-DIR
  769.      configure --host=sparc --target=sun3
  770.      make libgcc1.a
  771. And then this on the host machine:
  772.      ftp TARGET-MACHINE
  773.      binary
  774.      cd TARGET-BUILD-DIR
  775.      get libgcc1.a
  776.      quit
  777.    Another way to provide the functions you need in `libgcc1.a' is to
  778. define the appropriate `perform_...' macros for those functions.  If
  779. these definitions do not use the C arithmetic operators that they are
  780. meant to implement, you should be able to compile them with the
  781. cross-compiler you are building.  (If these definitions already exist
  782. for your target file, then you are all set.)
  783.    To build `libgcc1.a' using the perform macros, use
  784. `LIBGCC1=libgcc1.a OLDCC=./xgcc' when building the compiler.
  785. Otherwise, you should place your replacement library under the name
  786. `libgcc1.a' in the directory in which you will build the
  787. cross-compiler, before you run `make'.
  788. File: gcc.info,  Node: Cross Headers,  Next: Cross Runtime,  Prev: Tools and Libraries,  Up: Cross-Compiler
  789. Cross-Compilers and Header Files
  790. --------------------------------
  791.    If you are cross-compiling a standalone program or a program for an
  792. embedded system, then you may not need any header files except the few
  793. that are part of GNU CC (and those of your program).  However, if you
  794. intend to link your program with a standard C library such as `libc.a',
  795. then you probably need to compile with the header files that go with
  796. the library you use.
  797.    The GNU C compiler does not come with these files, because (1) they
  798. are system-specific, and (2) they belong in a C library, not in a
  799. compiler.
  800.    If the GNU C library supports your target machine, then you can get
  801. the header files from there (assuming you actually use the GNU library
  802. when you link your program).
  803.    If your target machine comes with a C compiler, it probably comes
  804. with suitable header files also.  If you make these files accessible
  805. from the host machine, the cross-compiler can use them also.
  806.    Otherwise, you're on your own in finding header files to use when
  807. cross-compiling.
  808.    When you have found suitable header files, put them in
  809. `/usr/local/TARGET/include', before building the cross compiler.  Then
  810. installation will run fixincludes properly and install the corrected
  811. versions of the header files where the compiler will use them.
  812.    Provide the header files before you build the cross-compiler, because
  813. the build stage actually runs the cross-compiler to produce parts of
  814. `libgcc.a'.  (These are the parts that *can* be compiled with GNU CC.)
  815. Some of them need suitable header files.
  816.    Here's an example showing how to copy the header files from a target
  817. machine.  On the target machine, do this:
  818.      (cd /usr/include; tar cf - .) > tarfile
  819.    Then, on the host machine, do this:
  820.      ftp TARGET-MACHINE
  821.      lcd /usr/local/TARGET/include
  822.      get tarfile
  823.      quit
  824.      tar xf tarfile
  825. File: gcc.info,  Node: Build Cross,  Prev: Cross Runtime,  Up: Cross-Compiler
  826. Actually Building the Cross-Compiler
  827. ------------------------------------
  828.    Now you can proceed just as for compiling a single-machine compiler
  829. through the step of building stage 1.  If you have not provided some
  830. sort of `libgcc1.a', then compilation will give up at the point where
  831. it needs that file, printing a suitable error message.  If you do
  832. provide `libgcc1.a', then building the compiler will automatically
  833. compile and link a test program called `cross-test'; if you get errors
  834. in the linking, it means that not all of the necessary routines in
  835. `libgcc1.a' are available.
  836.    If you are making a cross-compiler for an embedded system, and there
  837. is no `stdio.h' header for it, then the compilation of `enquire' will
  838. probably fail.  The job of `enquire' is to run on the target machine
  839. and figure out by experiment the nature of its floating point
  840. representation.  `enquire' records its findings in the header file
  841. `float.h'.  If you can't produce this file by running `enquire' on the
  842. target machine, then you will need to come up with a suitable `float.h'
  843. in some other way (or else, avoid using it in your programs).
  844.    Do not try to build stage 2 for a cross-compiler.  It doesn't work to
  845. rebuild GNU CC as a cross-compiler using the cross-compiler, because
  846. that would produce a program that runs on the target machine, not on the
  847. host.  For example, if you compile a 386-to-68030 cross-compiler with
  848. itself, the result will not be right either for the 386 (because it was
  849. compiled into 68030 code) or for the 68030 (because it was configured
  850. for a 386 as the host).  If you want to compile GNU CC into 68030 code,
  851. whether you compile it on a 68030 or with a cross-compiler on a 386, you
  852. must specify a 68030 as the host when you configure it.
  853.    To install the cross-compiler, use `make install', as usual.
  854.